This guide shows how to write a how-to guide to show how to use any type of resource that requires documentation.
To determine if you need to be writing documentation for a specific resource, you will need to consider: - the intended users of the resource, i.e. your target audience. - the range of technical know-how that can be expected from potential users. - the differential between expected users know-how and specific resource requirements.
For more details, please read our in-depth explanation. For the context of this how-to guide, it is sufficient that you define the three above elements for your use case. As an example, this guide would consider: - users to be part of a hiring team, whose purpose is to evaluate the current writer’s skills by reading this document. - having extensive experience writing documentation and/or a clear idea of what “good” documentation is (as well as a sense of what a “good” candidate would be for the role of technical author at Canonical). - resulting in a reversed differential, where users have more technical know-how than the author, who is nonetheless trying to show off some writing skills and self-referential awareness.
You will want to state, simply and concisely, the purpose of your how-to guide. Your readers should understand what you are going to demonstrate, and have confidence that you will be clear and methodical in doing so. As a mediocre example, this guide begins by stating that it will show how to write a how-to guide, but then admits to a second purpose of convincing users of the author’s hireability to a specific position. We suggest you don’t do that.
How detailed this list should be depends on the above three-point evalution. For instance, do you need to tell documentation specialists that in addition to a text editor (or IDE, I am currently using VSCode/Codium), you will need knowledge of at least one form of markup language (preferrably Markdown)? No, but you do need them to know that you know it, so it would be a good idea to mention it further down.
Similarly, an “input interface” for text will often be understood as a keyboard, but could also consist of voice-to-text software and hardware. We want our documentation to be accessible and inclusive.
You don’t expect the hiring team to actually follow along and write a how-to guide to show how to read and assess a self-referential how-to guide submitted as part of an application, so the text editor wasn’t really needed. Rather, a taste for “meta” humor definitely was, and probably a good dose of patience.
This is where the actual purpose of your guide becomes unavoidable. An example may be helpful:
This guide shows how to demonstrate an interest in the process and purpose of writing documentation, as well as critical thinking skills. Additionally, logical and abstraction skills would be indicated by the use of a “strange loop” structure, in the sense defined by Douglas Hofstadter.
Last modified: Tue Dec 9 10:44:31 2025